The mission map [event] section
This follows on immediately after the [building] section and before the [message] section in the .src map file = see my CF Map definitions (the previous page)
[event] Defines each 'event' for this mission Map
Most 'missions' will have dozens of 'events' (in theory, you could have up to 10,000 !). At the very least, the mission must have sufficient 'event' definitions to set the 'win' conditions for each player (i.e. type=score (+100), trigger = unitdestroyed (all))
Note that Events are not needed for basic building 'capture' effects. When a building changes hands, CF automatically changes the tile to the 'adjacent' one (in the Tile Definitions file, building icons must be defined in the order player1(brown,rebels), player2(blue,empire), {optional neutral}) and resets the ownership of all the Units inside
| [event] | Indicates an 'event' definition follows. Events provide a way to interact with players during a game. They can cause actions like 'points' being 'awarded' (you need 100 points to win a game) reinforcements being deployed and messages being displayed. Events can be 'triggered' by a timer or by player actions (capturing a building, occupying a specific map position, destroying an enemy unit etc) |
| id = | (0-10000), the unique event ID |
| type = | (event type), the following are available (see later for a full definition of each type). |
| configure | dynamically change the setting for various internal strings during the course of a game, e.g. the players' mission briefings. |
| createunit | create a (defined) unit at a defined position on the map. |
| destroyunit | removes a (defined) unit from the map. |
| manipulateevent | modify event internals. Currently this can be used to dynamically enable or disable an event. |
| message | display a message. |
| mining | set (change) the amount of crystals for a building. |
| research | add a new unit type to those available for production in a factory, or remove it from the list of available units. |
| score | award points to a player. |
| sethex | change a defined Terrain tile on the map. |
| settimer | adjust the timer trigger of another event. |
| player = | (1 | 2), the player to which this event will be applied |
| trigger = | (event trigger), the following are available (see later for a full definition of each trigger). Note that an event may have multiple triggers and will be executed once (only) when all the triggers are satisfied, although it is possible to 're-arm' (re-enable) an event using the 'manipulateevent' type |
| handicap | the event is executed if the set handicap matches the current game settings. Usually such an event is triggered immediately on the first turn or not at all. You can, however, combine multiple events (e.g. a handicap and a timer trigger) to change the default behaviour. |
| havebuilding | the event is executed when the player controls a certain building at a specified time. |
| havecrystals | the event is executed when the player owns (at least) the defined amount of crystals. |
| haveunit | the event is executed when the player controls a certain unit at a specified time. |
| timer | the event is unconditionally executed at the specified time. |
| unitdestroyed | the event is executed when a specified unit is destroyed or captured by the enemy. |
| unitposition | the event is executed when a specified unit ends its move on the defined map hex. |
| message = | (n), reference to a message (text block, counting from 0) to be displayed when the event occurs. |
| title = | (n), reference to the title (text block, counting from 0) string of the message window. |
| depend = | (n), identifier of another event on which the current event will depend. This event will execute only if the trigger = conditions for both events are successful. Mutual, circular, and transitive dependencies are supported. |
| discard = | (n), identifier of another event. When the current event is executed, the given event is discarded from the event stack and removed from the mission. |
| flags = | (1), used to disable this event until some other event (of type = manipulateevent) enables it |
type = definitions
Each type = and trigger = must be followed by it's definitions. These are :-
| type = configure | |
| setting = | (briefing1 | briefing2 | nextmap), setting to be changed. This is either the briefing 'objectives' for player1 (briefing1) or player2 (briefing2), or the next map (nextmap) for the next mission in the campaign. |
| value = | (n | file name), reference to the new message to be used as the new briefing (n) or the file name of the next mission (excluding the suffix) as appropriate. |
| type = createunit | Creates a single new Unit. Note that the units ID is assigned when it is created. This means it is virtually impossible reference a unit 'created' by an event (the ID assigned will be the first 'free' one) |
| unit = | (unit name), the 'type name' of the unit to be created the type names used are those specified in the Units Definitions (.usrc) file = if you change a unit name there, you MUST do a search and replace on all the Mission map .src files |
| size = | (1-6), unit group size. Optional, defaults to 6. |
| xp = | (0-6), experience level of the unit to be created. Optional, default no experience (0). |
| face = | (0-5), direction the created unit faces. Optional, default North (0). Directions are numbered clockwise from North (0) - NE (1) - SE (2) - S (3) - SW (4) - North-West (5) |
| pos = | (X tile)/(Y row), location to create the unit on. The unit will only be created if the target hex is empty at creation time or there is a building (or a valid transporter) which is controlled by the defined player = for this event |
| type = destroyunit | Removes a single Unit from play. The Unit counts as 'lost'. |
| unit = | (-1 | n), the ID (unique identifier) of the unit to be destroyed or (if set to -1) destroy the unit at the specified (pos =) map location (see also 'sethex') |
| pos = | (X tile)/(Y row), map location to destroy the unit on. The pos parameter can only be used if unit = -1. |
| owner = | (1 | 2 | -1), only destroy the unit if it is controlled by player1 (1) or player2 (2). Optional, default is any player (-1). |
| type = manipulateevent | Enable or disable another event. If the other event has been discarded (i.e. has already triggered), this event has no effect |
| event = | (n), identifier of the event (ID) to be modified. |
| action = | (0 | 1 | 2), set (0), clear (1) or toggle (2) the (specified) flag. |
| eflags = | (1), currently there is only one flag option, the 'event disabled' flag (1). Disabled events won't be triggered even if their trigger conditions are met. If enabled, and the trigger is found to be met, the event will trigger immediately. A timer event that has been disabled and then re-enabled after the specified trigger time has passed will immediately trigger |
| type = message | Display the text message specified in the event body |
| pos = | (X tile)/(Y row), map location to position (focus) the message pop-up box on (optional). If this parameter is absent the software will choose a suitable hex from the trigger data, e.g. a havebuilding trigger will cause it to use the building location |
| type = mining | Adjust the amount stored or rate of crystal generation. Minimum mining rate is 0, maximum is 200 |
| building = | (n), ID of the building to be adjusted |
| action = | (0 | 1 | 2 | 3), type of adjustment to be made0 = set the number of crystals currently stored to the specified amount 1 = adjust the number of crystals currently stored by the specified amount 2 = set the crystal generation (mining) rate to the specified amount 3 = adjust the current crystal generation (mining) rate by the specified amount |
| crystals = | (+/-n), specifies the amount of crystals |
| type = research | Modify the list of unit types that a factory can build |
| building = | (n), building identifier (building must be a 'shop' (factory) type) |
| unit = | (unit type), the name of a unit type (as defined in Units Definitions file) |
| action = | (0 | 1), allow (0) or disallow (1) the production of the specified unit type. Default is allow. |
| type = score | Adds to the players score. A player wins they have accumulated at least 100 points |
| success = | (1 to 100), the number of points added to the players total when the event is triggered. An Event triggers only once (unless manipulateevent is used to 're-arm' it). So if a player must achieve multiple goals 'at the same time' (eg capture and hold 2 (or more) buildings), a pair of (or chain of) 'depends' conditions can be used to prevent either (or any) score event being triggered until both (all) the conditions are met (there is no way to reduce a Players score) |
| othermsg = | (n), reference to a message to be shown to the opponent (optional) Avoids the need to create a separate message event (with inverted trigger conditions) to 'taunt' your opponent :-) |
| othertitle = | (n), reference to the message title string for the other player (optional, see othermsg) |
| type = sethex | Replace a terrain tile |
| pos = | (X tile)/(Y row), location of the map tile to be changed. If the tile is occupied by a unit at the time the event is executed, it may end up on terrain it would not normally be able to enter, however it can still exit to any adjacent terrain hex it is allowed into |
| tile = | (tile ID code), the ID code of the new terrain tile (see [map-raw]) |
| type = settimer | Adjust another events timer trigger Note that if the target event is disabled, settimer will automatically enable it. If the new setting for the other event puts it's trigger into the 'past', it will be triggered immediately |
| event = | (n), identifier of the event (ID) to be modified. |
| time = | (+/-n), time count. The offset setting controls how 'time count' is used to adjust the targeted trigger. |
| offset = | (0 | 1 | 2) Offset to use when adjusting the timer. 0 = absolute, i.e. set the trigger time to the value of the 'time count' 1 = relative, i.e. set the trigger to the current time plus the 'time count' 2 = modify, i.e. modify the existing trigger time by adding the 'time count' |
trigger = definitions
| trigger = handicap | The 'handicap' setting is chosen by the user at the start of the game (in the Mission selection / player choice dialogue box) |
| thandicap = | (1-5), the handicap setting that will trigger this event1 = trigger if no handicap was set 2 = trigger if player 1 handicap was set 3 = trigger if no or player1 was set (i.e. player2 is not handicapped) 4 = trigger if player 2 handicap was set 5 = trigger if no or player2 was set (i.e. player1 is not handicapped) |
| trigger = havebuilding | |
| tbuilding = | (n), building ID to be checked |
| towner = | (1 | 2), owner, player1 (1) or player2 (2) |
| ttime = | (-1 | n), time to check the building owner. Optional, default is all the time (-1). If all the time, triggers only when the ownership changes to the indicated player. If a specific time, triggers if the owner is found to be towner at that time. Time 0 = player1's first go, time 1 = player2's first go and so on |
| trigger = havecrystals | |
| towner = | (1 | 2), the player to be checked. Default is the player already mentioned in this event |
| tbuilding = | (n | -1 | -2), building ID to be checked (n), or check all buildings a player controls (-1) or check all buildings and all transporters (-2). |
| tcrystals = | (-5000 to +5000), the amount of crystals needed to trigger the event. If the amount is positive, the player needs at least that many crystals. If the amount is negative, the event is triggered when the player's resources drop below that absolute number |
| trigger = haveunit | Triggers when the specified player gains control of the specified Unit (see Note below) |
| tunit = | (n), unit ID to be checked |
| towner = | (1 | 2), player to check, player1 (1) or player2 (2) |
| ttime = | (n), time at which to check the unit owner. By default, if ttime is omitted, a check is made every turn. Time 0 = player1's first go, time 1 = player2's first go and so on |
| Note that the only way to 'capture' a unit is to capture the building it is in OR 'sweep' a Unit of type='mine' (whilst there are no 'neutral' unit colors, and no unit placed directly on the map can be set to anything other than player1 or player2, it is possible to define a non-moving 'mine' unit that can be picked up by either side with a 'sweeper' unit). When a unit is destroyed, neither player can ever gain control, so beware of linking this event to others with 'depends' | |
| trigger = timer | |
| ttime = | (n), time at which to execute the event. Time starts at 0 (at the start of a 'mission' = player1's first go) and increases by 1 each time the players change. For example, on play turn 10, the movement phase of player2 will be time = 19. |
| trigger = unitdestroyed | Triggers when the specified player 'no longer has control' of the specified unit (i.e. when the unit has been killed or captured (in a building, or, if of type 'mine', 'swept' (picked up) by the enemy)) |
| tunit = | (-1 | n | unit type), triggers when all units (-1) or a specified Unit ID is destroyed or when all of the specified type have been destroyed |
| towner = | (1 | 2), identifies which players units are to be checked. Optional if a player has already been identified (player =) for this event, otherwise required (if tunit = -1). |
| trigger = unitposition | |
| tpos = | (X tile)/(Y row), the map location to be checked |
| towner = | (1 | 2), triggers when a unit of player1(1) or player(2) occupies the defined map position. Default is player already identified in this event |
| tunit = | (-1 | n | unit type), triggers when any unit (-1) reaches the position, or only when a specific Unit ID (n) reaches the position, or when a unit of the specific type (eg Infantry) reaches the position |
Immediately following the map [event] definitions is the [message] section (which defines the messages for this mission map = see my Maps definitions (previous) page)